hyperspell-mcp

Instructions

Implementation Reference

• src/hyperspell_mcp/server.py:126-129 (handler)

  The main handler function for the 'Search Hyperspell' tool. It takes a query string, searches the Hyperspell API using the configured collection, and returns a list of Document objects.
  def query(query: str) -> list[Document]: """Search Hyperspell for documents and data.""" r = mcp.api.query.search(query=query, collections=mcp.config.collection) return Document.from_pydantic(r.documents)
• src/hyperspell_mcp/server.py:123-125 (registration)

  Registers the 'query' function as the MCP tool named 'Search Hyperspell' with its description.
  @mcp.tool( name="Search Hyperspell", description="Search Hyperspell for documents and data." )
• src/hyperspell_mcp/types.py:38-43 (schema)

  Dataclass schema defining the structure of each Document returned by the tool.
  class Document(BaseModel): id: int title: str type: str summary: str
• src/hyperspell_mcp/types.py:7-29 (helper)

  Helper class and method used to convert API responses (Pydantic models) to local dataclasses like Document.
  @dataclass class BaseModel: @overload @classmethod def from_pydantic(cls, model: PydanticBaseModel) -> Self: ... @overload @classmethod def from_pydantic(cls, model: Sequence[PydanticBaseModel]) -> list[Self]: ... @classmethod def from_pydantic( cls, model: PydanticBaseModel | Sequence[PydanticBaseModel] ) -> Self | list[Self]: """Convert a Pydantic model to a data class, selecting only the keys that are part of the data class.""" if isinstance(model, Sequence): return [cls.from_pydantic(m) for m in model] data = model.model_dump() # Only select the keys in data that are part of this data class data = {key: value for key, value in data.items() if key in cls.__annotations__} return cls(**data)